Skip Headers

Pro*C/C++ Getting Started 10g Release 2 (10.2) for Microsoft Windows (32-Bit) Part Number B14321-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 2 Using Pro*C/C++

This chapter explains how to create and precompile a project. It also explains how to use Pro*C/C++ at the command prompt.

This chapter contains these topics:

- Header Files

- Library Files

- Multithreaded Applications

- Precompiler Options

- Using Pro*C/C++ with the Oracle XA Library

  See Also: Pro*C/C++ Programmer's Guide for additional information

## Using Pro*C/C++ at the Command Prompt

To precompile a file at the command prompt, enter the following command:

    C:\> proc iname=filename.pc

where `filename``.pc` is the name of the file. If the file is not in your current working directory, include the file's full path after the INAME argument.

Pro*C/C++ generates `filename``.c`, which can be compiled by your C compiler.

## Header Files

The `ORACLE_BASE\ORACLE_HOME``\precomp\public` directory contains the Pro*C/C++ header files. Table 2-1 lists and describes the header files.

See Also: Pro*C/C++ Programmer's Guide for more information about `oraca.h`, `sqlca.h`, and `sqlda.h`.

Table 2-1 Header Files

Header Files | Description
--- | ---
`oraca.h` | Contains the Oracle Communications Area (ORACA), which helps you to diagnose runtime errors and to monitor your program's use of various Oracle Database 10g resources.
`sql2oci.h` | Contains SQLLIB functions that enable the Oracle Call Interface (OCI) environment handle and OCI service context to be obtained in a Pro*C/C++ application.
`sqlapr.h` | Contains ANSI prototypes for externalized functions that can be used in conjunction with OCI.
`sqlca.h` | Contains the SQL Communications Area (SQLCA), which helps you to diagnose runtime errors. The SQLCA is updated after every executable SQL statement.
`sqlcpr.h` | Contains platform-specific ANSI prototypes for SQLLIB functions that are generated by Pro*C/C++. By default, Pro*C/C++ does not support full-function prototyping of SQL programming calls. If you need this feature, include `sqlcpr.h` before any EXEC SQL statements in your application source file.
`oraca.h` | Contains the Oracle Communications Area (ORACA), which helps you to diagnose runtime errors and to monitor your program's use of various Oracle Database 10g resources.
`sql2oci.h` | Contains SQLLIB functions that enable the Oracle Call Interface (OCI) environment handle and OCI service context to be obtained in a Pro*C/C++ application.
`sqlapr.h` | Contains ANSI prototypes for externalized functions that can be used in conjunction with OCI.

## Library Files

The `ORACLE_BASE\ORACLE_HOME``\precomp\lib\msvc` directory contains the library file that you use when linking Pro*C/C++ applications. The library file is called `orasql110.lib`.

Pro*C/C++ application program interface (API) calls are implemented in DLL files provided with your Pro*C/C++ software. To use the DLLs, you must link your application with the import libraries (.lib files) that correspond to the Pro*C/C++ DLLs. Also, you must ensure that the DLL files are installed on the computer that is running your Pro*C/C++ application.

Microsoft provides you with three libraries: `libc.lib`, `libcmt.lib`, and `msvcrt.lib`. The Oracle DLLs use the `msvcrt.lib` runtime library. You must link with `msvcrt.lib` rather than the other two Microsoft libraries.

## Multithreaded Applications

Build multithreaded applications if you are planning to perform concurrent database operations.

Windows 2000, and Windows 98 schedule and allocate threads belonging to processes. A thread is a path of a program's execution. It consists of a kernel stack, the state of the CPU registers, a thread environment block, and a users stack. Each thread shares the resources of a process. Multithreaded applications use the resources of a process to coordinate the activities of individual threads.

When building a multithreaded application, make sure that your C/C++ code is reentrant. This means that access to static or global data must be restricted to one thread at a time. If you mix multithreaded and non-reentrant functions, one thread can modify information that is required by another thread.

The Pro*C/C++ precompiler automatically creates variables on the local stack of the thread. This ensures that each thread using the Pro*C/C++ function has access to a unique set of variables and is reentrant.

See Also: Pro*C/C++ Programmer's Guidefor additional information on how to write multithreaded applications with Pro*C/C++

## Precompiler Options

This section highlights issues related to Pro*C/C++ for Windows platforms.

See Also: "Precompiler Options" of Pro*C/C++ Programmer's Guide

### Configuration File

A configuration file is a text file that contains precompiler options.

For this release, the system configuration file is called `pcscfg.cfg`. This file is located in the `ORACLE_BASE\ORACLE_HOME\``precomp\admin` directory.

### CODE

The `CODE` option has a default setting of `ANSI_C`. Pro*C/C++ for other operating systems may have a default setting of `KR_C`.

### DBMS

`DBMS=V6_CHAR` is not supported when using `CHAR_MAP=VARCHAR2`. Instead, use `DBMS=V7`.

### INCLUDE

For sample programs that precompile with `PARSE=PARTIAL` or `PARSE=FULL`, an include path of `c:\program files\devstudio\vc\include` has been added. If Microsoft Visual C++ has been installed in a different location, modify the Include Directories field accordingly for the sample programs to precompile correctly.

### PARSE

The `PARSE` option has a default setting of `NONE`. Pro*C/C++ for other operating systems may have a default setting of `FULL`.

## Using Pro*C/C++ with the Oracle XA Library

The XA Application Program Interface (API) is typically used to enable an Oracle database to interact with a Transaction Processing (TP) monitor, such as:

- BEA Tuxedo

- IBM Transarc Encina

- IBM CICS

You can also use TP monitor statements in your client programs. The use of the XA API is also supported from both Pro*C/C++ and OCI.

The Oracle XA Library is automatically installed as part of Oracle Database 10g Enterprise Edition. The following components are created in your Oracle home directory:

Table 2-2 Oracle XA Library Components and Locations

Component | Location
--- | ---
`oraxa9.lib` | `ORACLE_BASE\ORACLE_HOME``\rdbms\xa`
`xa.h` | `ORACLE_BASE\ORACLE_HOME``\rdbms\demo`

### Compiling and Linking a Pro*C/C++ Program with XA

To compile and link a Pro*C/C++ program with XA:

1. Precompile `filename``.pc` using Pro*C/C++ to generate `filename``.c`.

2. Compile `filename``.c`, making sure to include `ORACLE_BASE\ORACLE_HOME``\rdbms\xa` in your path.

3. Link `filename``.obj` with the following libraries:

   Library | Location
   --- | ---
   `oraxa10.lib` | `ORACLE_BASE\ORACLE_HOME\``rdbms\xa`
   `oci.lib` | `ORACLE_BASE\ORACLE_HOME``\oci\lib\msvc`
   `orasql10.lib` | `ORACLE_BASE\ORACLE_HOME``\precomp\lib\msvc`

1. Run `filename``.exe`.

### XA Dynamic Registration

Oracle supports the use of XA dynamic registration. XA dynamic registration improves the performance of applications that interface with XA-compliant TP monitors.

For TP monitors to use XA dynamic registration with an Oracle database, you must add either an environmental variable or a registry variable to the Windows computer on which your TP monitor is running. See either of the following sections for instructions:

- Adding an Environmental Variable for the Current Session

- Adding a Registry Variable for All Sessions

#### Adding an Environmental Variable for the Current Session

Adding an environmental variable at the command prompt affects only the current session.

To add an environmental variable for the current session:

1. Go to the computer where your TP monitor is installed.

2. Enter the following at the command prompt:

       C:\> set ORA_XA_REG_DLL = vendor.dll

   where `vendor``.dll` is the TP monitor DLL provided by your vendor.

#### Adding a Registry Variable for All Sessions

Adding a registry variable affects all sessions on your Windows computer. This is useful for computers where only one TP monitor is running.

To add a registry variable for all sessions:

1. Go to the computer where your TP monitor is installed.

2. Enter the following at the command prompt:

       C:\> regedt32

   The Registry Editor window appears.

3. Go to `HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\HOME` `ID`.

4. Select the Add Value option in the Edit menu.

   The Add Value dialog box appears.

5. Enter `ORA_XA_REG_DLL` in the Value Name field.

6. Select `REG_EXPAND_SZ` from the Data Type list .

7. Click OK.

   The String Editor dialog appears.

8. Enter `vendor``.dll` in the String field, where `vendor``.dll` is the TP monitor DLL provided by your vendor.

9. Click OK.

   The Registry Editor adds the parameter.

10. Select Exit from the Registry menu.

    The registry exits.

### XA and TP Monitor Information

Refer to the following for more information about XA and TP monitors:

- Distributed TP: The XA Specification (C193) published by the Open Group. See the Web site at:

      http://www.opengroup.org/publications/catalog/tp.htm

- The Open Group., 1010 El Camino Real, Suite 380, Menlo Park, CA 94025, U.S.A.

- Your specific TP monitor documentation

  See Also: Oracle Database Application Developer's Guide - Fundamentalsfor more information about the Oracle XA Library and using XA dynamic registration